home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / button.n < prev    next >
Text File  |  1994-09-20  |  10KB  |  265 lines
  1.  
  2.  
  3.  
  4. button(n)                  Tk Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      button - Create and manipulate button widgets
  12.  
  13. SYNOPSIS
  14.      button _p_a_t_h_N_a_m_e ?_o_p_t_i_o_n_s?
  15.  
  16. STANDARD OPTIONS
  17.      activeBackground               bitmap          fontrelief     |
  18.      activeForeground               borderWidth     foregroundtext |
  19.      anchor          cursor         padX            textVariable   |
  20.      background      disabledForeground             padY           |
  21.  
  22.      See the ``options'' manual entry for details on the standard
  23.      options.
  24.  
  25. WIDGET-SPECIFIC OPTIONS
  26.      Name:           command
  27.      Class:          Command
  28.      Command-Line Switch:-command
  29.  
  30.           Specifies a Tcl command to associate with  the  button.
  31.           This  command  is typically invoked when mouse button 1
  32.           is released over the button window.
  33.  
  34.      Name:           height                                        |
  35.      Class:          Height                                        |
  36.      Command-Line Switch:-height                                   |
  37.  
  38.                                                                         ||
  39.           Specifies a desired height for the button.  If a bitmap  |
  40.           is being displayed in the button then the value  is  in  |
  41.           screen  units  (i.e.  any  of  the  forms acceptable to  |
  42.           Tk_GetPixels); for text it is in  lines  of  text.   If  |
  43.           this  option  isn't  specified,  the  button's  desired  |
  44.           height is computed from the size of the bitmap or  text  |
  45.           being displayed in it.                                   |
  46.  
  47.      Name:           state                                         |
  48.      Class:          State                                         |
  49.      Command-Line Switch:-state                                    |
  50.  
  51.                                                                         ||
  52.           Specifies  one of three states for the button:  normal,  |
  53.           active, or disabled.  In normal  state  the  button  is  |
  54.           displayed  using the foreground and background options.  |
  55.           The active state is typically used when the pointer  is  |
  56.           over  the  button.   In  active  state  the  button  is  |
  57.           displayed using the  activeForeground  and  activeBack-  |
  58.           ground  options.   Disabled state means that the button  |
  59.           is  insensitive:   it  doesn't  activate  and   doesn't  |
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. button(n)                  Tk Commands
  71.  
  72.  
  73.  
  74.           respond  to  mouse  button  presses.  In this state the  |
  75.           disabledForeground and background options determine how  |
  76.           the button is displayed.                                 |
  77.  
  78.      Name:           width                                         |
  79.      Class:          Width                                         |
  80.      Command-Line Switch:-width                                    |
  81.  
  82.                                                                         ||
  83.           Specifies  a desired width for the button.  If a bitmap  |
  84.           is being displayed in the button then the value  is  in  |
  85.           screen  units  (i.e.  any  of  the  forms acceptable to  |
  86.           Tk_GetPixels); for text it is in characters.   If  this  |
  87.           option  isn't  specified, the button's desired width is  |
  88.           computed from the size of  the  bitmap  or  text  being  |
  89.           displayed in it.
  90. _________________________________________________________________
  91.  
  92.  
  93. DESCRIPTION
  94.      The button command creates a new window (given by the  _p_a_t_h_-
  95.      _N_a_m_e  argument)  and  makes  it into a button widget.  Addi-
  96.      tional options, described above, may  be  specified  on  the
  97.      command  line or in the option database to configure aspects
  98.      of the button such as its colors, font,  text,  and  initial
  99.      relief.   The  button command returns its _p_a_t_h_N_a_m_e argument.
  100.      At the time this command is invoked, there must not exist  a
  101.      window named _p_a_t_h_N_a_m_e, but _p_a_t_h_N_a_m_e's parent must exist.
  102.  
  103.      A button is a widget that displays a textual string or  bit-  |
  104.      map.   It  can  display  itself in either of three different  |
  105.      ways, according to the state  option;  it  can  be  made  to
  106.      appear raised, sunken, or flat; and it can be made to flash.
  107.      When a user invokes the button (by pressing mouse  button  1
  108.      with  the  cursor  over  the  button),  then the Tcl command
  109.      specified in the -command option is invoked.
  110.  
  111.  
  112. WIDGET COMMAND
  113.      The button command creates a new Tcl command whose  name  is
  114.      _p_a_t_h_N_a_m_e.  This command may be used to invoke various opera-
  115.      tions on the widget.  It has the following general form:
  116.  
  117.           _p_a_t_h_N_a_m_e _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  118.  
  119.      _O_p_t_i_o_n and the _a_r_gs determine the exact behavior of the com-
  120.      mand.   The following commands are possible for button widg-
  121.      ets:
  122.  
  123.      _p_a_t_h_N_a_m_e activate
  124.           Change the button's state to active and  redisplay  the
  125.           button  using  its  active  foreground  and  background
  126.           colors instead  of  normal  colors.   This  command  is  |
  127.  
  128.  
  129.  
  130. Tk                                                              2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. button(n)                  Tk Commands
  137.  
  138.  
  139.  
  140.           ignored  if  the button's state is disabled.  This com-  |
  141.           mand is obsolete and will eventually  be  removed;  use  |
  142.           ``_p_a_t_h_N_a_m_e configure -state active'' instead.
  143.  
  144.      _p_a_t_h_N_a_m_e configure ?_o_p_t_i_o_n? ?_v_a_l_u_e _o_p_t_i_o_n _v_a_l_u_e ...?
  145.           Query  or  modify  the  configuration  options  of  the
  146.           widget.   If  no  _o_p_t_i_o_n  is  specified, returns a list
  147.           describing all of the available  options  for  _p_a_t_h_N_a_m_e
  148.           (see  Tk_ConfigureInfo for information on the format of
  149.           this list).  If _o_p_t_i_o_n is specified with no _v_a_l_u_e, then
  150.           the  command  returns  a  list describing the one named
  151.           option (this list will be identical to the  correspond-
  152.           ing  sublist  of  the  value  returned  if no _o_p_t_i_o_n is
  153.           specified).  If one  or  more  _o_p_t_i_o_n-_v_a_l_u_e  pairs  are
  154.           specified,  then  the command modifies the given widget
  155.           option(s) to have the given value(s);  in this case the
  156.           command  returns  an empty string.  _O_p_t_i_o_n may have any
  157.           of the values accepted by the button command.
  158.  
  159.      _p_a_t_h_N_a_m_e deactivate
  160.           Change the button's state to normal and  redisplay  the
  161.           button  using  its  normal  foreground  and  background
  162.           colors.  This command is ignored if the button's  state  |
  163.           is disabled.  This command is obsolete and will eventu-  |
  164.           ally be removed; use ``_p_a_t_h_N_a_m_e configure  -state  nor-  |
  165.           mal'' instead.
  166.  
  167.      _p_a_t_h_N_a_m_e flash
  168.           Flash the button.  This is accomplished by redisplaying
  169.           the  button  several  times, alternating between active
  170.           and normal colors.  At the end of the flash the  button
  171.           is  left  in  the  same normal/active state as when the
  172.           command was invoked.  This command is  ignored  if  the  |
  173.           button's state is disabled.
  174.  
  175.      _p_a_t_h_N_a_m_e invoke
  176.           Invoke the Tcl command associated with the  button,  if  |
  177.           there  is  one.   The  return value is the return value  |
  178.           from the Tcl command, or an empty string if there is no  |
  179.           command  associated  with  the button.  This command is  |
  180.           ignored if the button's state is disabled.
  181.  
  182.  
  183. DEFAULT BINDINGS
  184.      Tk automatically creates class  bindings  for  buttons  that  |
  185.      give them the following default behavior:                     |
  186.  
  187.      [1]                                                                ||
  188.           The  button activates whenever the mouse passes over it  |
  189.           and deactivates whenever the mouse leaves the button.    |
  190.  
  191.      [2]                                                                ||
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. button(n)                  Tk Commands
  203.  
  204.  
  205.  
  206.           The button's relief is changed to sunken whenever mouse  |
  207.           button 1 is pressed over the button, and the relief  is  |
  208.           restored  to  its original value when button 1 is later  |
  209.           released.                                                |
  210.  
  211.      [3]                                                                ||
  212.           If  mouse button 1 is pressed over the button and later  |
  213.           released over the button, the button is invoked.   How-  |
  214.           ever, if the mouse is not over the button when button 1  |
  215.           is released, then no invocation occurs.                  |
  216.  
  217.      If the button's state is disabled then  none  of  the  above  |
  218.      actions occur:  the button is completely non-responsive.      |
  219.  
  220.      The behavior of buttons can be changed by defining new bind-  |
  221.      ings for individual widgets or by redefining the class bind-  |
  222.      ings.
  223.  
  224.  
  225. KEYWORDS
  226.      button, widget
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Tk                                                              4
  262.  
  263.  
  264.  
  265.